Developer CD Series 1999 July: Mac OS SDK

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / Apple Game Sprockets / InputSprocket 1.4 SDK / InputSprocket Release Notes < prev next >

Wrap

Text File | 1998-11-30 | 20.8 KB | 448 lines | [ttro/ttxt]

InputSprocket 1.4f1 Release Notes ------------------- For a detailed list of changes from the previous version, please read the change list at the end of this document. Please report all bugs using the bug reporter on Apple Developer Connection: <http://developer.apple.com/bugreporter/index.html> Release Components ------------------ InputSprocketLib The main InputSprocket library InputSprocket CH CH Jetstick, CH Flightstick Pro, CH Pro Pedals, CH Pedals, CH F16 Fighterstick, CH Gamepad, CH Pro Throttle InputSprocket CH Trackball support for CH Trackballs InputSprocket Contour support for the Contour Mouse InputSprocket Gravis Gravis Gamepad, Gravis Firebird, Gravis Mousestick II, Gravis Blackhawk InputSprocket Kensington Kensington TurboMouse 4.0, TurboMouse 5.0, Thinking Mouse, Kensington Mouse, CoStar Stringray trackball InputSprocket Keyboard standard Keyboard driver InputSprocket MacALLY support for the MacALLY Joystick InputSprocket Microspeed support for MacTRAC and MouseDeluxe InputSprocket Mouse standard Mouse driver InputSprocket NoHandsMouse support for the NoHands mouse InputSprocket SideWinder 3D Pro support for SideWinder 3D Pro InputSprocket Speech support for Apple Speech Recognition InputSprocket Thrustmaster Thrustmaster FCS, Thrustmaster WCS, Thrustmaster RCS InputSprocket USB support for some USB devices on a Mac with USB USBHIDUniversalModule This library is required for the USB support InputSprocketDebugLib Debug build of InputSprocket InputSprocket CH Debug Debugging driver InputSprocket CH TrackballDebug Debugging driver InputSprocket Contour Debug Debugging driver InputSprocket Gravis Debug Debugging driver InputSprocket Kensington Debug Debugging driver InputSprocket Keyboard Debug Debugging driver InputSprocket MacALLY Debug Debugging driver InputSprocket Microspeed Debug Debugging driver InputSprocket Mouse Debug Debugging driver InputSprocket NoHandsMouseDebug Debugging driver InputSprocket SideWinder Debug Debugging driver InputSprocket Speech Debug Debugging driver InputSprocket ThrustmasterDebug Debugging driver InputSprocket USB Debug Debugging driver InputSprocket NeedView A special debugging driver to show your application's needs. InputSprocket AppleJack AppleJack/ Pippin Controller InputSprocket ArenaMouse Extra drivers not part of standard install InputSprocket AppleJack Debug Debug build InputSprocket ArenaMouse Debug Debug build InputSprocket.h Required header for applications. InputSprocket.r Rez templates for appliciations InputSprocketDriver.h Required header for drivers InputSprocketDefer.h Required header if the driver uses the deer libary InputSprocketLib link libraries InputSprocketStubLib link libraries ISpDeferLib link libraries USBManagerLib link libraries UniversalHIDModule.h USB headers USB.h USB headers Writing an ISp Driver.pdf Documentation for building an InputSprocket driver WARNING: don't place both the debugging and non-debugging versions of the library in the search path or you will not be sure which version you are using. Dependencies ------------ InputSprocket requires the latest Universal Headers -- You can find them with the latest version of your development environment, Apple's WWW and FTP sites or the developer CD-ROMs. InputSprocket needs a 640x480 display (or larger) in order for its dialog to work. If you are asking DrawSprocket for a smaller display size than that you should switch out before calling InputSprocket. Compatibility with Previous Releases ------------------------------------ InputSprocket 1.4 should be fully compatible with previous releases of InputSprocket. Changes from 1.3 to 1.4 ----------------------- This version adds support for many new USB devices: Saitek Cyborg 3D stick, KYE/Genius Joystick and Gamepad, Edge/Rockfire Joysticks (2), and gamepads (3). The need label kISpElementLabel_Btn_PauseResume has been replaced with two new labels: kISpElementLabel_Btn_Quit and kISpElementLabel_Btn_StartPause. This is to clarify the purpose and default behavior intended by a need. The quit need defaults to '<esc>' on the keyboard and can only be changed to 'Cmd Q'. This need quits an active game, or quits the application entirely. The start/pause need corresponds to the action that a 'start' button on a gamepad would have, which is often pause. Gamepads and other devices with a button labeled 'start' should default to the start/pause need. On a keyboard, the start/pause need can be mapped to any key, unlike the quit need. There is a hack to allow calibration of USB devices. Essentially, the first time you configure a device, you should roll the controller to the maximum extents possible. InputSprocket will memorize the values being returned by the controller and use these to calibrate it. Changes from 1.2 to 1.3 ----------------------- A resource definition file "InputSprocket.r" has been added. You can use this file to create a Rez '.r' file to build the ISp resources into your application. One of the templates is for the 'tset' resource created by the ISp keyboard driver. Note this templete is ONLY valid for a 'tset' generated by the keyboard. The only way to tell who created the 'tset' is to examine the 'setl' resource that points to it. The new sample code for DroneZone uses this template so that the defaults for the keyboard are in a Rez file and are easily updated when then application's list of needs changes. You still have recreate the sets for mice and gaming devices when your needs list changes during development, but not having to re-setup all the keyboard keys every time should be a big win. (Note: You may have to delete your InputSprocket Preferences file in order to get the new defaults from the application -- or change the subCreatorCode passed to ISpInit.) Special thanks to Jeremy Erwin who is not affiliated with MacALLY, for the code to support the MacALLY stick. All mice and keyboard drivers are 'passthru' in the debug versions. This means that it is VERY important you make sure you also test with the release versions of the drivers, since some things will work fine with the debug versions but not with the release drivers. On the other hand, you will never get stuck in the debugger without being able to type and/or move the cursor. InputSprocket resets all elements to 'zero' values (symmetric axis are reset to the center) across suspend/resume. It is the responsibility of individual ISp drivers to push data to any elements which are non-default valued when the driver is reactivated. Many minor bugs have been fixed. 68K support has been added. 68K InputSprocket is only available through CFM-68K. Changes from 1.1 to 1.2 ----------------------- This release involves many minor improvements to the InputSprocket drivers, including an improved user interface (UI) for axis. Some new drivers have also been added. Several problems and bugs have been addressed. A new resource has been defined (kISpApplicationResourceType = 'isap') which all applications which use InputSprocket should put (ID 0) in their resource fork. They should always set bit 0 (kISpAppResFlag_UsesInputSprocket) and set bit 1 (kISpAppResFlag_UsesISpInit) if they use the high level API (ie they call ISpInit, ISpConfig, etc... in other words they have a needs list). The rest of the bits and reserved fields should be set to 0. A new ISpElementKind has been added: kISpElementKind_Delta which specifies a Fixed point number of inches moved. InputSprocket Mouse and InputSprocket Kensington now register elements of this kind in the low level. The high level (through ISpConfigure) supports axis as well as delta kinds. This kind is very useful if you want to control a cursor. A new definition of ISpNeed can be used by defining USE_OLD_ISPNEED_STRUCT to 0. The first reserved field (a short) was changed to two UInt8s: playerNum and group. Use playerNum to tell the driver some needs are related to a particular player (on the same machine). The SprocketInvaders source code will be reved to use this field. Group is used to group items together, such as a look up, look down need (assuming you can't use an axis). You should also group items together that have the same effect, but are 'tuned' button, axis, and delta versions. The current ISp drivers do not use this hinting, yet. Some new definitions for the ISpNeedFlagBits have been added. If you use the new definition, make sure you check your code for cases where you were initializing the struct. You now may be misaligned, and many compilers will NOT generate a warning. InputSprocket Mouse supplies pseudo-buttons in the high level for modifier keys in combination with mouse clicks. You will have at least four buttons (where some may actually be command/shift/control/option-click on one-button mice) for any mouse device. This should make it straightforward to port games which expect a two button mouse: use ISp with delta and button needs -- and dont worry about what type of device the user has. InputSprocket Speech added back to distribution (crashing bug fixed) - InputSprocket Gravis supports Blackhawk and uses new UI (new save set format) - InputSprocket Thrustmaster uses new UI (new save set format) - InputSprocket Joy completely revised, renamed InputSprocket CH, now supports multiple devices seperately and supports up to 8 buttons and 4 hats per device (new save set format) - InputSprocket Kensington added, supports kensington devices regardless of their software - InputSprocket Sidewinder 3D Pro added, supports Microsoft Sidewinder joystick - InputSprocket AppleJack added, supports Pippin/AppleJack controller - InputSprocket Keyboard supports modifier keys in conjunction with a normal key (now either Escape or Cmd-Q are valid for kISpElementLabel_Btn_PauseResume) - Device and element strings have been reviewed, and some have been changed - ISpConfigure saves and restores the port. - A new function: ISpTimeToMicroseconds has been added. - There are some new bits defined for ISpNeedFlagBits. - Some new element labels have been added. - Old saved sets for devices other than mouse and keyboard do not work Known Problems in 1.2 --------------------- - Kensington Mouse-in-a-box reports two buttons (only the first one works) - ALPS GlidePoint does not appear if ALPS software is installed (appears w/o ALPS software) - Mouse Systems Mouse does not appear if Mouse Systems software ('3-Button Power') is installed (appears as 1 button mouse w/o Mouse Systems software) - CH Trackball PRO does not appear - Thrustmaster software generates keyDowns if so configured with ThrustWare (fix is to configure all buttons to do nothing in ThrustWare) - Machines based on the Tanzania motherboard (Motorola StarMax, APS MPower, Apple PowerMacintosh 4400) will always show an extra Mouse device for the PS/2 mouse regardless whether one is plugged in (even though the 4400 has no PS/2 ports, the phantom ADB devices for them are still created). The PS/2 mouse only reports one button. - When a Sidewinder 3D Pro stick is connected, an extra mouse device is shown which is active when the 'mouse/joystick' switch is switched to 'mouse'. - It is unstable to have multiple applications use InputSprocket simultaneously. If your application can be suspended and uses InputSprocket you should use ISpShutdown and ISpStartup so that InputSprocket is off while you are in the background. This is a bug (since 1.0) and will be fixed in the next version. If you are a user you can work around this problem by not running more than one InputSprocket application at the same time. - When debugging, you may need to deactivate the Mouse and Keyboard drivers in order to be able to interact with your debugger. Changes from 1.0.2 to 1.1 ------------------------- Known Problems in 1.1 --------------------- - Kensington Trackball does not appear if Kensington software is installed (appears w/o Kensington software) - ALPS GlidePoint does not appear if ALPS software is installed (appears w/o ALPS software) - Mouse Systems Mouse does not appear if Mouse Systems software ('3-Button Power') is installed (appears as 1 button mouse w/o Mouse Systems software) - CoStar Stingray Trackball does not appear if CoStar software ('Stingray') is installed (appears w/o CoStar software) - CH Trackball PRO does not appear - Thrustmaster software generates keyDowns if so configured with ThrustWare (fix is to configure all buttons to do nothing in ThrustWare) Changes from 1.02 ----------------- - new APIs (ISpStartup, ISpShutdown, ISpTickle, ISpDevices_ActivateClass, ISpDevices_DeactivateClass) - some general UI improvements in both appearance and performance have been made - new driver InputSprocket Joy (supports some features of JoyManager devices -- ie mainly CH products) - new driver InputSprocket Thrustmaster (supports FCS, WCS, RCS) - new driver InputSprocket Gravis (supports MouseStick, Firebird, GamePad) - new driver InputSprocket Speech (you must activate explicitly and requires ISpTickle be called) - InputSprocket Mouse changed to have new UI and is implemented via ADBMgr directly instead of a CursorDeviceMgr Patch - InputSprocket Keyboard has been slightly changed if there is only one page - driver function to plot icons has been changed (faster) - bug when you select a 0 length name to save a set has been fixed - bug involving choosing monitor has been fixed (might chose something other than the main monitor randomly) - CH Flightstick, CH Gamepad, CH Jetstick and MacEnjoy no longer generate a mouse device - a crashing bug involving multiple applications using input sprocket simultaniously has been fixed - a very small memory leak involving ISpConfigure has been fixed - DONT_USE_OLD_INPUT_SPROCKET_LABELS changed to USE_OLD_INPUT_SPROCKET_LABELS in InputSprocket.h - a bug where InputSprocket Keyboard and InputSprocket Mouse called InitGraf has been fixed Other notes: - you must call ISpTickle in order for InputSprocket Speech to work - you must call ISpDevices_ActivateClass(kISpDeviceClass_SpeechRecognition) to turn InputSprocket Speech on - requires SpeechRecognition extension 1.5.1 (PlainTalk 1.5) InputSprocket Joy Notes ----------------------- - supports all JoyManager devices as a single input sprocket device. - UI may show popups for controls the device does not have - JoySimpleData based - only supports the trigger and three additional buttons - digital pointing devices (ex. CH Gamepad's pad) are treated as a pair of axis not a POV Hat Changes from 1.0 and 1.0.2 Release Notes ---------------------------------------- There is a new InputSprocket.h that has new versions of the names for the labels as well as additional labels. The following bugs were fixed in the 1.01 or the 1.02 releases. - keyboard UI now generates better names than Min/Max for axis if ElementLabel is useful - various problems with alignment and growing of dialog were fixed - flickering with icons in thrustmaster and mouse fixed - stub library included in this release with file type 'stub' - axis flipping check box now works again for the mouse driver - ISpDevices_Extract functions no work when an exact count is passed to them - Icon plotting is more robust. - The OK button is no longer hilited when the keyboard is active. - InputSprocket will now unload the drivers when the last fragment is unloaded - InputSprocket no longer leaks memory when you quit in the suspended state - when there are no devices to configure and ISpConfigure is called it will display a warning instead of doing nothing - ISpSuspend no longer leaks 10,000 bytes every call The following bugs are known: -There is an incompatability with the mouse driver and the Kensignton trackball software that causes no mice devices to appear. -There is a incompatability with the Kensington trackball that causes an extra mouse device to appear when the hardware is installed and the software is not installed. InputSprocket Clarifications and Guidelines ------------------------------------------- Although not a change, a clarification is needed on how exclusive items operate particularly with regards to hat-type switches (direction-pads, digital joysticks and hat switches). A group of mutually exclusive items is a group of items where activation of one item automatically deactivates other items in the group. A group of mutually exclusive items might be assigned to a hat. An example is "look" functionality which allows the user to different directions from the cockpit in a flight simulator implemented as four different button needs. A problem will arise if the group of items only uses the activation of these buttons to select which item is active. This problem will only arise if the program in question does not properly handle combinations of the button activations. For example, if I assign "look right" to the right item of a hat and "look forward" to the top item of a hat. Now, if I press right on the hat I will look right. If I now wiggle my thumb upwards so that up is activated (up and right are now simultaneously activated) I will look forward. If I slide my thumb back to the right, I will release the "look up" item, but since the "look right" item was activated the whole time, I do not reactivate the "look right" function. I now have my thumb holding the hat right, but I am looking forward. In fact, since the "look right" item is already held down, it is the ONLY button on the entire controller which cannot be pressed and it becomes impossible to look right without releasing the hat and pressing it right again. Symptoms of this are that it is easier to look right by pressing forward and sliding right to the corner of the d-pad than it is to press right directly! The only way to correct for this is to consider both presses (kISpButtonDown) and releases (kISpButtonUp) of any button needs which are exclusive. In this case, when right is pressed, the right function would be activated. When the up function is activated, both items are now activated. The InputSprocket client can either deactivate the original right function and switch to the up function, or it can remain with the right function and only switch to the up function when the right button is released. If the hat is moved to the right again and the up function is released, then the client should switch back to the right function if it has switched away. Proper handling of releases of button needs will allow mutually exclusive functions to operate properly. Before you ship any application, check to make sure you get no warnings when running with InputSprocketDebugLib and the debug versions of the drivers. We recommend that if you are using InputSprocket version greater than 1.02 that you no longer support any third party joystick APIs. You must not support those APIs at the same time as you have InputSprocket devices enabled. If you are using InputSprocket via the high level (ISpConfigure and ISpInit and so on), We recommend that you only use the axis and button data types and build the controls that you need out of those types. This will get you the best support. Many of the drivers are going to only primarily emulate those datatypes. Your game may provide default and optional configurations for the keyboard, the mouse and any other devices. This is done by including 'setl' and 'tset' resources a resource file, such as the application's, that is open when ISpInit and ISpConfigure are called. Since the format of the 'tset' resource is determined by the device, it is easiest to use the configuration dialog to establish the desired configurations then copy them from the Preferences file into your resource file. 1. Remove the InputSprocket Preferences file from the Preferences folder. 2. Run your game, and invoke the ISpConfigure dialog. 3. Configure and save as many sets as you like for any and all devices. 4. Quit. 5. Use ResEdit to move the 'setl' and 'tset' resources to your resource file. 6. Edit the 'setl' resource using the 'TMPL' supplied in InputSprocketSimpleTest.rsrc. 7. Change the flags field to $00000002 for the default entry for a given device or $00000004 for any other entry for that device. 8. Again remove the InputSprocket Preferences file from the Preferences folder so you can test with a clean slate. 9. Rebuild your game and try out your new configurations. Alternatively, Rez templates are now provided for all InputSprocket resources. ISp drivers must insure that they are VM safe. ADB drivers can link to InputSprocketDeferLib to insure their ADB handlers are executed at a time where it is safe to page. The new sample ADB driver does this.